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Abstract 

Soar>mode  is  a  major  mode  within  the  GNU-Emacs  editor.  It  provides  an  integrated,  stnKtured  editor  for  editing, 
ranning,  and  debugging  Soar  models  on  the  production  level.  Productions  are  treated  as  first  class  objects.  With 
keystrolQB  (or  menu)  commands  productions  can  be  directly  loaded,  examined,  and  queried  about  their  cunent  match 
status.  Listings  of  the  productions  that  have  fired  or  are  about  to  fire  can  be  automatically  displayed.  Soar-mode 
includes  and  organizes,  for  the  first  time,  comfriete  on-line  documentation  on  Soar  and  a  simple  browser  to  examine 
this  information. 
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Overview 


As  a  minimal  description,  soar-mode  provides  the  following  features: 

•  A  structured  edibH'  for  Soar  productions  and  loading  them  directly  into  a  ruiuiing  Soar  interpreter. 

•  The  ability  to  treat  Soar  problem  spaces  and  operators  as  levels  in  an  outline,  performing  the  usual 
outline  processing  functions  on  them. 

•  Commands  to  test  and  examine  productions  bound  to  keys  and  mouse  buttons  that  are  smart  enough  to 
tell  which  productions  they  ate  in  (»-  over. 

•  Complete  on-line  documentation  for  Soar,  soar-mode,  the  Soar  default  productions,  and  the  Soar  source 
code. 

•  Functions  to  generate  and  maintain  informative  source  code  file  headers. 

•  Tags  file  support  for  Soar  productions  (i.e.,  find-production-source-code)  to  enable  fast  and  easy 
retrieval  of  production’s  source  code. 

•  Support  for  running  one  or  more  Soar  processes  in  separate  buffers,  and  commands  for  interacting  with 
these  subprocesses. 

•  Support  for  Common  Lisp  programming  (this  may  disappear  in  later  releases). 


Obtaining  latCT  versions  of  this  manual 

Updated  versions  of  Soar-mode  and  this  manual  are  available  via  anonymous  FTP 
from  centro.soar.cs.cmu.edu  [128.2.242.24S].  The  README  file  in 
/afs/cs/project/soar/public/SotffS  (or  /afs/cs/^ject/soar/public/Soar6)  will 
provide  you  with  a  listing  of  the  latest  versions,  and  which  fdes  to  pull  to  get  them. 
Note:  CMU’s  machines  do  not  allow  you  to  access  intermediate  directories  in  this  path. 

Requests  for  clarifications  or  bug  reports  should  be  sent  to  soar-bugs@cs.cmu.edu. 

DISCLAIMER 


The  Developmental  Soar  Interface  is  placed  in  the  public  domain.  You  are  free  to  copy  it  as  you  wish.  The 
Developmental  Soar  Interface  and  all  of  its  parts:  Soar  in  X  (SX),  taql-mode,  and  soar-mode,  (like  Soar  itself)  are 
made  available  AS  IS,  and  Carnegie  Mellon  University,  the  University  of  Michigan,  and  its  developers,  make  no 
warranty  about  the  software  or  its  performance.  Please  contact  soar-bugs@cs.cmu.edu  for  more  information  or  to 
report  problems. 


Some  of  the  supporting  software  comes  with  different  copyright  conditions.  Soar-mode  and  taql-mode  use 
several  utility  programs  that  are  protected  under  the  Free  Software  Foundation’s  Copyleft  agreement. 
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1.  Design  philosophy 

This  short  section  provides  a  conceptual  overview  of  soar-mode  and  motivation  for  the  current  approach.  Eager 
users  can  skip  it  The  following  sectitms  describe  soar-mode  in  detail. 

Soar  programmers  develop  applications  in  a  cycle  that  typically  consists  of  the  following  phases: 

1.  Create  an  initial  conceptual  description  of  a  task. 

2.  Map  the  conceptual  description  into  the  Soar  computational  model. 

3.  Create  a  set  of  Soar  productions  implementing  the  task.  This  actually  can  involve  several  substeps: 

a.  create  source  text  files  containing  subsets  of  the  task  productions. 

b.  write  the  productions,  following  certain  style  and  naming  conventions,  and 

c.  intosperse  descriptive  comments  throughout  the  source  text  files. 

4.  Run  Soar  and  incrementally  define  the  set  of  productions  to  the  Soar  interpreter,  entering  a  cycle  that 
ends  when  the  task  is  running: 

a.  read  productions  into  Soar. 

b.  collect  error  messages  and  examine  Soar’s  behavior, 

c.  edit  productions  and  go  to  (a). 

The  first  two  steps  require  much  intuition  and  soul-searching  on  the  part  of  the  Soar  programmer,  during  these 
stages  not  much  programming  actually  takes  place.  The  3rd  and  4th  steps  are  computer-intensive.  They  require  at 
least  two  sqrarate  program  components,  a  text  editor  and  a  Soar  interpreter,  and  considerable  time  expenditure  on 
the  part  of  the  programmer. 

Until  recently  the  3rd  and  4th  phases  were  not  well  integrated.  A  number  of  attempts  have  been  made  at 
providing  beasx,  more  integrated  Soar  programming  environments  embodying  these  phases  for  Unix  systems: 
Blake  Ward’s  1987  electric-soar-mode,  Milnes  and  Shevis’s  original  soar-mode,  Olin  Shivers  soar-mode 
scaffolding,  and  Frank  Ritter’s  recent  Hypersoar-mode.  Alt  were  based  on  Emacs-style  editors.  A  customizable 
editor  such  as  Emacs  provides  a  good  substrate  for  integrating  the  phases  together.  By  using  a  Lisp  subsystem 
supported  by  Emacs  one  can  create  a  structured  editor  that  understands  properties  specific  to  Soar. 

This  new  soar-mode  integrates  all  of  the  features  and  ideas  from  Ward’s,  Shevis’,  Shivers’,  Ritter’s  and  Hucka’s 
modes,  along  with  new  facilities,  on  top  of  an  extensive  Lisp  mode  called  ILISP  by  Chris  McConnell,  and  parts  of 
Franz  Inc.’s  mode  fw  their  Allegro  Common  Lisp.  It  is  nothing  if  not  extensive,  but  we  have  tried  to  make  it 
accessible  also. 
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2.  GNU-Emacs  typing  conventions 

If  you  are  terribly  familiar  with  GNU-Emacs.  you  could  skip  this  section.  If  you  are  not.  it  will  behoove  you  to  at 
least  quickly  scan  it,  for  it  is  quite  necessary  for  understanding  the  keystroke  notations  used  in  later  sections. 

You  should  Erst  note  that  GNU  Emacs  is  case  sensitive.  For  consistency,  all  Emacs  commands  in  this  mode  are  in 
lower  case.  When  a  conunand  is  called  "taql-insert-constmct",  it  can  not  be  typed  in  as  "TAQL-insert-constnict". 
TAQL  and  Soar  are  only  capitalized  when  they  denote  Soar  or  the  Task  Acquisition  Umguage  themselves. 

The  standard  GNU  Emacs  conventions  for  specifying  control  characters  are  used.  For  example,  "C-c  C-t" 
rqtresents  holding  down  the  control  key  and  typing  ”c”  and  then  holding  down  the  control  key  and  typing  "t". 
(Control  characters  are  not  case  sensitive,  that  is,  C-C  is  the  same  as  C-c.)  Spaces  (and  other  whitespace  characters 
like  tab)  are  rqnesented  by  their  name  in  broken  brackets,  for  example,  <TAB>.  Escape  key  sequences  are  denoted 
by  "M-"  for  meta,  because  some  keyboards  will  actually  have  a  meta  key  that  can  be  held  down,  shifting  all  keys  to 
meta  just  like  control  does.  Keyboards  without  this  feature  provide  escape,  a  way  to  preface  a  single  key  as  meta. 
For  example,  typing  <escape>  and  then  "x"  is  represented  by  M-x.  Sometimes  escape  may  also  be  denoted  by 

Typing  C-g  at  any  point  in  GNU  Emacs  will  abort  the  current  action.  This  is  also  true  in  the  Soar  and  TAQL 
sub-modes  where  C-g  will  abort  commands  cleanly.  For  example,  typing  C-g  while  completing  a  template  will 
leave  the  template  in  a  state  that  further  expansion  will  correctly  fill  it  in. 

Many  of  the  soar-  and  taql-mode  commands  begin  with  the  Soar  Command  Prefix  (SCP)  that  can  be  set  by  the 
user.  This  prefix  is  used  to  avoid  clashing  with  other  key  bindings  and  yet  remain  flexible.  The  default  value  is 
C-c.^  (If  you  use  C-c  to  bind  other  commands,  you  can  specify  another  character,  such  as  C-6  which  is  not 
otherwise  used  in  Emacs.)  Code  to  set  the  SCP  to  another  character  is  shown  in  the  defaults  file  described  below. 

Open  and  close  delimiters  are  counted  for  you.  These  include  all  those  delimiters  in  Soar  used  only  as  delimiters; 
that  is.  all  those  in  this  string:  "OQO"*  We  don’t  treat  <  and  >  as  delimiters  because  they  are  also  used  in 
preferences  and  could  thus  be  miscounted.  When  you  type  a  close  delimiter,  the  corresponding  open  delimiter  will 
be  flashed:  the  cursor  will  briefly  move  back  to  the  open  delimiter,  or  if  it  is  not  currently  displayed,  the  line  that  it 
occurs  on  will  be  displayed  in  the  message  line. 

The  kevbindings  described  below  are  only  provided  when  the  buffer  is  in  soar-mode.  At  all  other  times,  after  the 
initialization  file  has  been  loaded  and  soar-mode  has  been  called  at  least  once,  you  can  execute  commands  by  typing 
"M-x  command-name". 


‘C.6  was  to  be  the  default,  but  it  appean  that  some  Iceyboaids  can't  generate  it. 
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3.  Commands  for  editing  Soar  flies 

Buffen  containing  files  of  Soar  source  code  (and  ending  in  .soar  or  .soarS  or  .soaifi)  are  automatically  put  into 
soar-mode  by  the  commands  in  the  default  init  file.  When  such  a  file  is  read  into  an  Emacs  buffer  it  is  automatically 
put  into  soar-mode,  which  binds  several  keys  to  new.  Soar  specific  functions.  The  most  important  of  the  initial 
bindings  are  listed  below.  Each  conunand  normally  works  on  the  production  the  cursor  is  in  or  just  after.  Keys  can 
be  rebound  by  users  (for  an  example,  see  the  default  init-file).  A  complete  and  current  listing  is  available  on-line  by 
typing  C-h  m,  or  individual  keys  can  be  tested  by  C-h  k  (key  sequence).  Where  possible  (and  feasible),  commands 
that  apply  to  productiois  also  apply  to  TC's. 


Opaentlons  on  peoductiona  nnd  regions: 

C-c  •  Eval  production  or  function  (i.e.,  send  to  running  Soar) 

BSC  C-x  (alternative  binding) 

C-c  C-e  Eval  production  or  function  and  goto  the  Soar  buffer 

C-c  f  Find  production  source  code  (using  tags) 

ESC  .  Find  function  source  code  (using  tags) 

(standard  version,  not  customized  for  productions) 

C-c  r  Eval  region 

C-c  C-r  Eval  region  and  goto  the  Soar  buffer 
C-c  n  Eval  next  s-expresslon  (l.e.  production) 

C-c  C-n  Eval  next  production  and  goto  the  Soar  buffer 
C-c  c  Show  production  soar-pclass 

C-c  p  Print  object  around  or  before  point  (using  spr) 

C-c  X  Excise  production 

C-c  w  Copy  production  (or  TC)  to  kill  buffer.  C-y  will  Insert  a  copy. 


Tracing  operations; 

C-c  B  Pbreak  production  (with  arg,  e.g.  C-u,  unpbreak) 

C-c  t  Ptrace  production  (with  arg,  e.g.  C-u,  unptrace) 


Match  Information: 

C-c  m  Smatches  on  production 

C-c  M  Full-matches  on  production 


Movement  conmands; 

ESC  C-a  Go  to  beginning  of  production 

BSC  C-e  Go  to  the  end  of  production 

ESC  C-b  Go  backward  one  clause  (or  s-expresslon) 

ESC  C-f  Go  forward  one  clause  (or  s-expresslon) 

BSC  C-k  Kill  next  clause  (or  s-expresslon) 

C-c  C-z  Zwltch  to  the  Soar  buffer, 

with  arg  (l.e.,  C-u)  go  to  end  of  the  Soar  buffer 
C-c  b  Same  as  C-c  C-z. 


Mlsc.  source  file  editing  commands: 

BSC  ;  Start  an  In-line  coonent 

C-c  ;  Comment -region,  will  put  prefix  number  of  copies  of 

before  the  lines  In  region,  to 
uncomnent  a  region,  use  a  minus  prefix  (e.g.,  C-u  -  3  C-c  ;) 
Load  file  into  Soar 
Run-soar,  start  up  a  Soar 


C-c  1 
C-c  C-1 
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Ruxmlng  coimuinds 

Th«8«  coomuids  all  us*  th*  sasM  dafault  axg  (soax-dafault-dxm-arg) , 
which  can  b*  s*t  In  your  .asiacs  £11*.  It  is  initially  1,  that  is:  (d 
1),  (r  1)  and  (nacrocycla  1) .  It  is  updated  after  each  use.  An  arg 
of  0  sets  th*  default  to  nil  (i.e.,  (d) ,  (r)  and  (macrocycle) ) . 

(ESC-x  8oar-r\u-task  also  uses  this  arg.) 

C-c  .  (d  arg) 

C-c  ,  (r  arg) 

C-c  SPC  (macrocycle  arg) 


Oseful  functions  from  Coianon  Lisp  mode: 

C-c  t  Trace  a  Lisp  function 

(untrac*  when  given  argximent,  i.e.,  C-u) 

]  Close  all  open  parentheses  (i.*.>  a  "super-)") 

up  to  first  [ 

C-c  )  Find  unbalanced  Lisp  parenthesis 

M-j  Insert  new  comment  line  (if  in  a  comment) ,  or  a  plain  newline 

if  not. 


Other  effective  standard  Emacs  commands: 

BSC  /  Auto  cooplete 

C-/  Undo  (can  be  repeated  multiple  times) 


Reset  and  help  functions: 

C-c  C-c  Interrupt  the  running  Soar  or  Lisp 

C-c  z  Pop  out  of  all  break (s)  to  top  level  in  the  Soar  or  Lisp  buffer 

C-d  Pop  out  of  single  break  in  the  Soar  or  Lisp  buffer 

M-x  panic-lisp 

Panic  reset  for  the  inferior  LISP  or  Soar 
C-c  C-m  Run  the  soar-mode  cosnand  menu 
C-h  m  Describe  th*  current  mode,  e.g.  soar-mode 

C-c  d  Get  Lisp  documentation  string  for  syabol  under  point 

C-c  D  Look  up  Common  Lisp  function  under  point  in  reference  manual 

C-c  A  J^ropoa  for  Cosnon  Lisp  functions 


These  last  two  commands  provide  a  buffer  of  information  on  the  selected 
item.  In  this  buffer  "a"  is  bound  to  apropos,  "m"  to  manual  lookup,  "s" 
to  search-forward-see-alsos,  and  "C-c  C-c"  to  flush-doc. 


Outline  functions 


Soar-mode  allows  th*  user  to  collapse  blocks  of  productions  into 
problem  spaces  and  operators  labeled  headings,  like  working  with  an 
outline  processor. 

Blocks  of  text  and  productions  beginning  with  ";  6problem-space 
name"  or  goperator  name"  can  be  collapsed  into  a  single  line  "; 
gproblem- space  name  .  .  .  " .  Operator  blocks  collapse  as  children 
nodes  of  problem  spaces  as  shown  in  this  axasple: 

;  0problem-space  top-space 
;  goperator  top-operator  . . . 

;  ©operator  near-top-operator  . . . 

;  ©problem-space  lower-space  . . . 

Problem  space  and  operator  labels  that  are  indented  two  spaces 
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collaps*  an  additional  layar  down.  Through  this  mechanism,  problem 
spaces  can  be  nested  within  other  problem  spaces  and  operators. 

The  functions  to  manipulate  the  parents  and  children  are  Included  on 
the  soar-a»de  menu  under  outl/,  and  bound  to  keys.  The  default 
kej^lndlngs  begin  with  C-x.  This  Is  a  user  setable  warlable,  and  Is 
Included  In  the  soar-mode-def suits . el  file.  The  most  frequent  used 
cosmands  are  likely  to  be  hide-node  (C-s  C-c  C-h)  and  show  node  (C- 
X  C-c  C-s)  .  If  users  find  these  ke^lndlngs  unwieldy,  there  are 
examples  of  how  to  rebind  functions  to  keys  In  the  soar-mode- 
def  suits,  el  file 

If  the  tag  Sproblem-space  (and  0operator)  Is  Indented  further  than 
one  space,  they  are  treated  as  lower  levels,  one  level  for  every  two  spaces  of 
indention. 

Extended  commands: 


In  addition,  a  number  of  other  commands  are  not  bound  to  keys  but  are  available  as  extended  commands  (that  is, 
to  execute  them  type  ESC-x  command-name); 


run-soar  or 
soar 


soar6 


make-header 

make-revlslon 


make-tags-table 
remake-tags -table 


flnd-tags-table 


Start  up  a  SoarS  process  by  calling 
soar-image-name.  You  can  set  this  In  your 
.emacs  file.  The  default  value  Is  "SoarS". 

Beeps  when  things  are  set  up. 

Start  up  a  SoarS  process  by  calling 
soarS-laage-name . 

Creates  a  buffer  with  the  productions  that 
are  currently  matched.  With  just  soar-mode,  the 
buffer  Is  updated  after  every  elaboration  cycle. 
With  the  SX  display  the  rate  Is  adjustable. 

Insert  file  header  Into  current  buffer. 

Add  a  revision  line  to  header. 

After  soar-mode  has  been  loaded,  these  two 
commands  can  also  be  called  when  In  other  modes . 
See  below  for  more  information. 

Make  a  tags  table,  prompting  for  a  list  of  files. 
Update  a  tags  table,  replacing  entries  only  for 
files  that  have  changed  since  the  TAGS  file  was 

saved. 

Switch  tags  table  files. 


soar-count -productions  Count  the  number  of  productions  in  current  buffer, 

soar-list -product ion -names 

Collect  the  names  of  all  productions  in  buffer 
and  output  in  other  window. 

insert-date-string  Insert  the  date  after  point,  e.g.,  "5-27-91  -" 

If  Insert -date-wlth -month-name  is  not  nil,  month 
name  is  used  and  day/month  order  is  shifted, 
e.g.  "27-May-91". 

insert -time-string  Insert  the  time  in  military  format  after  point, 

e.g.,  "1457". 

insert -current -time-string  Insert  the  full  current -time -string  after  point, 

e.g.,  "Mon  May  27  15:00:57  1991". 

inspect-lisp  These  two  f\inctions  will  call  inspect  or  describe 
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dascrlbtt-llsp 


on  th*  current  s-tti^rosslon,  or  whon  called  with 
an  argument  will  prompt  for  the  object. 


0 -argument  Soar  commands 


0 -argument  DSI  commands 


run-task 


macroexpand-llsp 


All  argumentless  Soar  commands,  such  as  pgs  are 
available  as  M-x  commands.  For  exasple, 

"N-x  excise-task". 

The  arguBientless  DSI  commands  load-taql  and 
sx  are  available  as  M-x  commands.  For 
exasple,  "M-x  sx”  will  start  up  the  comnand 
Interpreter  loop. 

User  defined  function.  The  soar-mode  version 
passes  a  numeric  argument,  soar-default-drm-arg, 
which  Is  used  and  set  In  the  same  way  as  for  the 
soar-mode  version  of  d,  r  and  macrocycle  (see 
"Running  Commands"  above) . 

Macro  expansion  (also  available  on  Lisp  menu) . 


This  package  modifies  the  Emacs  variable  auto-mode-alist  so  that  the  major  modes  defined  in  this  package  are 
invoked  when  certain  types  of  source  files  are  read  into  Emacs.  The  list  of  filename  extensions  given  by  the  value 
of  "soar-file-types"  causes  soar-mode  to  be  invoked  whenever  a  file  with  one  of  these  extensions  is  visited.  The 
default  extensions  are  .soar  and  .soarS,  but  more  can  be  added.  Any  buffer  may  be  put  into  soar-mode  by  calling  the 
function  soar-mode  interactively  (e.g.,  by  doing  "ESC-x  soar-mode"). 


Delete  now  converts  tabs  to  spaces  as  it  moves  back. 


Mouse  Siinport 

When  running  a  separate  GNU  window  under  X  windows,  soar-mode  defines  special  functions  for  the  mouse 
buttons.  These  button  bindings  will  not  work  when  using  GNU  with  the  -nw,  no  (separate)  window,  option.  If  you 
set  mouse  buttons  in  your  window  manager’s  init  file,  you  may  clobber  these  definitions  because  the  window 
maitager’s  settings  will  probably  have  priority. 

BUTTOH  FONCTION 


left 

middle 

right 


[  These  are  not  set  by  soar-mode,  but  are  ] 
[  left  for  the  user  to  set.  Typically  they] 
C  set  point,  paste,  and  select  text.  ] 


SHIFT- left 

SHIFT-mlddle 

SHIFT-rlght 


Run  Soar  "spr"  on  Item  under  cursor 

Run  Soar  "full -matches"  on  Item  under  cursor 

Run  find-tag  on  Item  under  cursor 


CONTROL-left 

COMTROL-mlddle 

COMTROL-rlght 


Load  definition  (Soar  or  Lisp)  under  cursor 

Run  Soar  "ptrace"  on  Item  under  cursor 

[  available  for  future  ei^anslon  or  user  settable  ] 


File  Headers  in  Soar 


Soar-mode  provides  extensive  support  for  file  headers.  A  file  header  is  a  descriptive  comment  block  placed  at  the 
beginning  of  a  source  code  file  to  keep  track  of  such  infonnation  as  the  author,  creation  date,  last-modified  dale,  and 
soon. 


To  make  a  header  for  the  file  in  the  current  buffer,  execute  the  command  "M-x  make-header".  This  inserts  a 
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standard  header  at  the  ti^  of  the  bufler.  based  on  the  current  mode  (it  will  work  for  non-soar  buffers  too)  and  the 
functions  listed  in  the  variable  ’’make-header-hodcs".  The  default  configuration  of  "make-header"  would  create  the 
following  header  for  a  file  named  "testsoar": 

;;;;  Mods:  Soar 


; ; ; ;  File  :  test . soar 

; ; ; ;  Author  ;  Joe  User 

;;;;  Created  On  :  Thu  Mar  29  14:12:46  1990 

;  ;  Last  Modified  By: 

; ; ; ;  Last  Modified  On : 

; ; ; ;  O^pdate  Count  :  0 

; ; ; ;  Soar  Version  :  5.1 

; ; ; ;  PUBPOSE 

;;;;  I >Descrlptlon  of  module's  purpose<| 

; ; ; ;  TABLE  OF  COMTEMTS 
; ; ; ;  I >Contents  of  this  module< | 

; ; ; ;  <tab>  header  1 
; ; ; ;  <tab>  header  2 

;;;;  (use  tab  so  you  don't  have  to  remember  number  of  spaces) 

;;;;  (C)  Copyright  1992,  University  of  Flchlgan,  all  rights  reserved. 

And  if  you  use  the  header-status  and  header-history  lines  (the  default),  this  is  tacked  on  at  the  end; 

;;;;  Status  :  Unknown,  Use  with  caution! 

;;;;  HISTORY 
0  0  0  0 

000000000000000000000lt00f0llt0t$tt000000000000t0f0t0000ff0t0lt00t000ttt0l0t0l 

If  you  use  RCS,  the  header  ends  like  this: 

; ; ; ;  $Locker$ 

; ; ; ;  $Log$ 

000000000000000000000000000000000000000000000000000000000000000000000000l0000f 

You  must  fill  in  the  PURPOSE,  TABLE  OF  CONTENTS,  Status,  and  HISTORY  entries  yourself.  When  you 
save  a  file  containing  a  header  created  by  "make-heado'”,  and  soar-mode  has  been  loaded  (or  the  header  files  have 
been  loaded  by  you  or  some  other  mode),  the  "Last  Modified  By",  "Last  Modified  On"  and  "Update  Count"  fields 
are  automatically  updated.  We  expect  this  will  be  the  primary  way  file  headers  are  updated. 

The  "SLockerS"  and  "SLogS"  fields  are  used  by  RCS,  a  more  advanced  way  of  updating  files.  If  you  use  RCS  to 
maintain  your  source  files,  the  RCS  commands  will  automatically  generate  the  appropriate  information  in  those 
fields. 

The  fields  that  are  used  are  taken  from  the  header-elemcnts-list  variable,  which  you  can  set  in  your  .cmacs  file. 
The  default  value  is  shown  in  the  soar-mode-defaults.el  file  included  with  this  distribution  in  the  directory  above  this 
manual  (and  also  in  this  manual,  below).  For  example,  you  could  remove  the  history  and  status  line  from  that  list 


When  in  the  middle  of  a  block  comment,  "M-j"  will  break  the  current  line  at  the  cursor  point,  then  indent  to  the 
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same  column,  continuing  the  comment.  If  you  are  not  in  the  middle  of  a  comment  "M-j"  will  add  a  new  line  and 
indent  (as  will  CR). 


Using  the  TAGS  Features 

The  Emacs  "tags"  facility  provides  the  means  to  quickly  locate  the  source  code  for  a  symbol.  Standard  GNU 
Emacs  supports  "tags"  files  for  C.  Lisp  and  a  few  other  languages.  Once  a  tags  file  has  been  selected,  the  keystroke 
"M- ."  (meta-dot)  over  a  symbol  will  move  the  cursor  to  the  source  for  that  function. 

Soar-mode  adds  support  for  tagging  the  SP  form  of  Soar  productions.  A  "tags  table"  is  a  list  of  tuples  of  <name, 
nie,  position>,  describing  how  function  and  variable  declarations  of  a  multi-file  program  are  separated  into  source 
files.  For  each  name  (the  "tag"),  the  file  in  which  the  name  is  defined  and  the  position  in  the  file  is  recorded  in  the 
tags  table.  The  file  which  stores  the  tags  table  is  called  a  "tags  table  file"  and  its  conventional  name  is  "TAGS". 

Using  the  tags  feature  of  soar-mode,  it’s  possible  to  create  a  tags  table  file  listing  all  the  productions  in  a  task. 
The  simplest  way  to  generate  this  file  is  to  use  the  function  "make-tags-table".  It  prompts  for  the  names  of  the 
source  Hie  and  the  name  of  the  TAGS  table  to  be  created.  Therefore,  if  you  have  a  directory  full  of  .soar  files  you 
would  like  to  "tagify",  you  could  do  the  following; 

ESC-x  make-tags-table  <CR>  /pathname/*  .soar  <CR>  /paihname/TAGS  <CR> 

Once  the  tags  file  has  been  constructed,  you  can  use  it  to  quickly  locate  the  source  code  of  a  production  if  you 
have  its  name.  To  look  up  the  definition  of  a  production  (or  Lisp  function  or  variable  or  whatever),  first  position  the 
cursor  over  the  name  of  the  production,  and  then  type  "C-c  C-f  which  invokes  the  find-tag  function.  (The 
almost-equivalent  alternative,  "ESC-."  (so  called  "meta  dot")  is  retained  for  compatibility  with  normal  Emacs/Lisp 
key  bindings.) 

This  feature  works  in  both  Soar  subprocess  buffers  and  Soar  text  buffers.  Thus  you'ean  lookup  the  definition  of  a 
production  whose  name  you  see  printed  anywhere  in  the  buffer  (provide,  of  course,  the  appropriate  tags  table  has 
been  built) 

A  suggestion:  whenever  you  built  a  tags  table  for  a  set  of  Soar  files,  include  in  the  list  of  filenames 
~soar/src/defaulLsoar.  This  often  comes  in  handy  when  you  see  default  productions  firing  and  you’re  wondering 
what  they  are  doing. 

The  function  "remake-tags-table"  can  be  used  to  update  a  TAGS  file  for  a  set  of  files. 

Sometimes  you  will  need  to  switch  tags  table  files.  The  function  "find-tags-table"  will  prompt  you  for  the  name 
of  a  new  tags  table  to  use. 

The  function  "tags-apropos"  will  display  a  list  of  all  tags  matching  a  given  regular  expression  in  the  current  tags 
table. 
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4.  Getting  help 

Hdp  on  the  current  buffer's  set  of  key  bindings  and  state  variables  (the  mode)  is  always  available  by  typing 
"C-h  m"  in  GNU  Emacs.  This  presents  help  on  what  commands  are  generally  available  in  the  current  buffer  (the 
one  the  cursor  is  in),  and  often  a  brief  statement  about  the  major  mode’s  general  orientation. 

The  manual  you  are  reading  now  is  available  on-line  in  the  soar-mode  distribution  directory  in  manuals/soar- 
mode-manual.doc  (as  text)  and  soar-mode-manual.ps  (PostScript  version).  The  command  menu,  available  through 
C-c  C-m,  provides  you  with  a  list  of  manuals  under  the  "Doc"  menu  item. 

Help  is  also  available  for  Soar  commands.  Soar  commands  are  essentially  Common  Lisp  functions,  and  as  such, 
their  descriptions  are  available  under  the  standard  get-dcscription-string  command  in  soar-mode.  The  default 
binding  of  this  command  in  soar-mode  is  "C-c  d". 

If  you  encounter  what  you  think  is  a  bug,  you  can  (and  should)  generate  a  report  automatically  by  typing 
"M-x  soar-bug".  (This  command  is  also  available  in  the  menu.)  You  should  send  this  report  by  mail,  using 
whatever  mail  program  you  normally  use. 
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5.  Loading  and  running  soar-mode 

To  use  soar-mode,  load  the  file  soar-mode-defaults.el.  Its  directory  is  dependent  on  your  site.  At  CMU  (and 
other  AFS  sites)  you  can  just  put  the  following  statement  in  your  .emacs  file: 

(load  7afs/cs.cmu.edu/project/soar/5.2/emacs/soar/{soar-mode-release)/soar-mode-defaults.el") 

Then,  when  you  want  to  edit  a  file  of  Soar  productions  (ending  in  .soar  or  .soar6),  simply  read  the  file  normally 
into  Smacs  and  the  buffer  automatically  will  be  put  into  soar-mode.  Similarly,  if  you  edit  a  Lisp  file  (ending  in 
.lisp),  ILISP  alone  will  get  loaded. 

If  you  don’t  like  the  default  settings  set  by  soar-mode-defaults,  and  there  are  enough  that  you  should  view  this  file 
when  you  start  to  use  soar-mode  more,  put  customizations  in  your  .emacs  file  after  the  command  to  load  the 
defaults,  overwriting  them.  You  could  also  insert  the  contents  of  the  soar-mode-defaults  file  into  your  .emacs  file, 
and  make  the  appropriate  changes  there. 

To  run  Soar  as  a  subprocess,  invoke  the  command  "run-soar"  or  just  "soar"  by  typing  "M-x  soar".  The  normal- 
appearing  Soar  process  will  start  up  in  a  window  of  Emacs.  If  you  use  several  versions  of  Soar,  such  as  the  Soar5 
and  Soar5+sx,  you  can  use  the  example  code  in  soar-mode-defaults.el  to  choose  between  them  at  start  up. 

Once  you’re  editing  a  file  of  Soar  code  or  running  Soar,  type  "C-h  m"  for  help  on  Emacs  soar-mode,  or  "C-c 
C-m"  for  the  soar-mode  menu. 

Before  you  exit  Emacs,  you  should  quit  the  Soar  process  as  you  would  normally.  Not  doing  so  is  normally  safe, 
but  it  relies  on  Emacs  successfully  killing  the  Soar  job  when  Emacs  exits,  which  does  not  always  happen. 

Soar  and  soar-mode  are  not  small  programs.  Old  Emacs  versions  (18.57  and  older)  can  run  out  of  address  space, 
and  are  more  likely  to  do  so  when  you  run  these  programs.  The  best  answer  is  to  use  a  newer  Emacs.  If  you  cannot 
do  so,  as  a  preventative  measure  you  should  exit  and  restart  Emacs  more  often,  particularly  if  you  examine  large 
files. 

If  Emacs  does  crash,  don’t  panic.  Your  modified  files  should  be  backed  up  as  #file-name#  in  their  normal 
directory.  You  can  edit  them,  and  when  you  save  them,  they  are  written  out  without  the  surrounding  pound-sign  (#) 
characters. 


Modifying  soar-mode  through  hooks 

A  hook  is  a  place  to  hang  either  a  function,  or  a  list  of  functions  that  get  executed  after  a  specific  corresponding 
event  occurs.  They  allow  you  to  customize  soar-mode  to  suit  yourself,  particularly  if  you  want  to  do  something  to 
each  file  or  Soar  process.  They  are  implemented  as  Lisp  variables,  so  you  can  put  functions  or  lambda  expressions 
on  them  just  as  you  would  add  to  any  list.  The  table  below  shows  when  hooks  get  called,  and  their  calling  order. 


Kaynaps  and  thair  ralatlonahlpa : 
Kaynap  to  changa  or  changaa 
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Hook(s)  to  use 


soar-moda-map  soar-mode-load-hook 

This  Is  usad  In  soar-moda,  on 
filas  of  Soar  productions. 

i soar-moda -map  soar-mode-load-hook  -or-  soar-hook 

This  is  usad  in  the  buffer 
running  Soar. 

Choosing  a  Soar  program  to  run: 

-  each  time  Soar  is  called  soar-hook 

-  at  start  of  session  only  soar-mode-load-hook 

i lisp-mode -map  ilisp- load-hook 

coBiint -mode -map  lisp-mode-hook 

1 i sp -mode -map 

These  are  the  underlying  keymaps 
soar-mode  is  built  on.  Leave  them 
alone  unless  you  are  running 
stand-alone  Lisp  too. 

Hooks  you  may  want  to  use  (Advanced  version) : 

Event  Hooks  called  (in  order) 


soar-mode  loaded  ilisp-site-hook,  ilisp-load-hook, 

soar-oiode-site-hook,  soar-mode-load-hook 

soar-mode  entered  lisp-mode-hook,  soar-mode-hook 

inferior-soar  mode  started  ilisp-mode-hook, 

(Soar  started  up)  <dialect>-hook  (e.g.,  allegro-hook), 

soar-hook,  comint -mode -hook 

Executed  after  inferior  Soar  ilisp-init-hook 

(or  lisp)  is  initialized 

lisp-mode  entered  lisp-mode-hook,  comint -mode -hook, 

lisp  started  up  ilisp-mode-hook,  clisp-hook, 

<dialect>-hook  (e.g.,  allegro-hook) 
comint -mode -hook 

soar-after-ilisp-hook 

For  example,  consider  the  following  code.  In  addition  to  changing  a  few  small  things,  it  queries  you  each  ume 
you  start  up  about  which  image  to  run,  a  plain  Soar  image,  or  the  Soar+sx  image; 
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(8«tq  soar-hook 
'  (  (lanbda  () 

; ;  this  could  be  done  on  soar-mode-load-hook  just  as  well  and  faster 
(setq  soax-date-wlth-sionth-nasie  t) 

(If  (and  (not  (coodnt-check-pxoc  ''*soar*"}) 

(y-ox-n-p  "Use  SoarS-t-sx (y)  or  plain  Soax5  (n)  ?  ")} 

(setq  lllsp-pxogxam 

"/afs/cs/project/soar/5. 2/src/sx/5 . 1 . l/Soax5+sx.acli") 
(setq  lllsp-pxogxam 

"/afs/cs/pxoject/soar/5.2/2/bln/pmax/mach/franz/Soar5") ) 
(setq  tab- width  4) ) 


Installing  soar-mode  at  a  remote  site 

Updated  versions  of  Soar-mode  and  this  manual  are  available  via  anonymous  FTP  firom  cenao.soar.cs.cmu.edu 
[128.2.242.24S].  The  README  file  in  /afs/cs^Moject/soar/public/SoarS  (or  /afs/cs/pioject/soar/public/Soar6)  will 
provide  you  with  a  listing  of  the  latest  versions,  and  which  files  to  pull  to  get  them.  Note:  CMU’s  machines  do  not 
allow  you  to  access  intermediate  directories  in  this  path. 

In  those  directories,  the  complete  source  for  soar-mode  is  mostly  likely  still  named  ”soar-mode.<soar-mode- 
version>.tar.Z'’.  You  can  copy  this  file  directly  if  you  are  at  Michigan  or  ISI,  or  you  can  retrieve  it  via  anonymous- 
FTP. 

You  should  move  it  into  the  directory  it  will  live  in.  We  suggest  putting  it  in  the  directory  (soar-on-your- 
sy  stem )  /soar-mode/  { soar-mode- version ) . 

You  must  uncompress  it  (uncompress  soar-mode. tarZ)  and  untar  it  (tar  xf  soar-mode.tar).  You  then  must  change 
the  following  variables  in.the  indicated  files: 
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ril*  Varlabl* 


soar-moda-defaults . el  soar-mode-home-dlrectoxy 


Mew  Value 


Mew  untared  directory  name 


soar-site. el  soar-mode-hone-directory 

soar-image-name 

In  file  section  IV, 
paths  pointing  to 
manuals  &  source 

header-copyright -notice 
def dialect -soar. el  " (def dialect  soar”  args 


comint  -prompt  -regexp 


comint-prompt-regexp 

"yovar  Soar  prompt") 


ilisp/<varsion>/soar . lisp 


Mew  untared  directory  name 
What  you  call  Soar 
(Soars  is  default) 

Local  paths  for: 

Soar  source  file 
Soar  bibliography  file 
default  productions  file 
Your  name  or  site  name 
Lisp  version  that  Soar  is 
based  on,  e.g..  Lucid. 
Allegro  is  the  default. 

A  regular  e3q>ression  that 
matches  the  prompt  when 
Soar  is  xrtinning.  A  good 
check  to  make  is  to 
evaluate  (string-match 


and  verify  that  it  returns 
0  (If  the  call  returns 
nil,  you  must  edit  the 
value  of  the  variable  to 
match  your  prompt) . 

Code  you  want  to  be  loaded 
each  time  Soar  starts  up, 
such  as  as  (init-soar) . 
For  format,  see  file. 


Recompiling  the  emacs  code.  After  you  have  set  the  above  variables,  you  should  recompile  the  Emacs  files  so 
soar-mode  runs  faster.  In  a  separate  X  GNU-Emacs  window  (not  a  gnu  -nw  window),  you  must  first  load  soar- 
mode-defauIts.el  (by  calling  ESC-x  load-file  soar-mode-defauits.el},  then  load  soar-mode  (ESC-x  soar-mode),  and 
then  compile  it  (ESC-x  soar-compile-soar-mode).  This  recompile  may  prompt  you  to  confirm  each  file  compilation 
and  you  should  always  answer  "y".  It  should  take  less  than  5  minutes  to  do,  and  subsequent  loading  and  running 
will  be  consitterably  faster.  Note  to  Epoch  users:  Before  recompiling,  you  should  rename  ilisp/<version>/cpoch- 
pop-el  to  ilisp/<version>/epoch-pop.el . 

Recompiling  the  lisp  code.  Disp  loads  some  common  lisp  files  into  SoarS  when  it  starts  up.  Users  at  remote  sites 
should  compile  them  on  their  own  after  the  emacs  code  has  been  compiled.  To  start  this  procedd,  bring  up  an 
inferior  Soar  process  (ESC-x  soar)  and  then  typing  "ESC-X  ilisp<ompile-inits".  It  uses  an  extension  for  binaries 
that  makes  them  appropriate  and  unique  to  the  machine  and  LISP  implementation.  So  after  you  have  started  up 
Soar,  you  need  to  call  M-x  ilisp-compile-inits  only  once  for  each  machine/lisp  combination.  This  may  be  slightly 
screwy,  and  if  it  queries  you,  you  may  have  to  answer  ("n"  seems  good  so  far).  You  can  also  compile  the  files  by 
hand  if  you  don’t  figure  it  out.  The  distributed  version  includes  source  files  to  load  into  and  set  up:  Allegro,  Lucid, 
CMULisp,  and  K(X. 

If  you  have  problems  getting  soar-mode  up  because  it  appears  to  be  in  an  endless  loop  initializing,  the  problem  is 
probably  that  soar-mode  can  not  recognize  your  local  Soar  prompt  Even  if  you  don’t  know  how  to  read  regular 
expressions,  you  can  check  to  see  that  comint-prompt-regexp  in  the  defdialect  in  defdialect-soar.cl  matches  your 
prompt  with  string-match  (see  note  in  table  above).  Examples  of  some  prompts  that  will  be  matched  by  the  default 
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value  of  comint-prompt-regexp  are  "<cl>  ”,  "<soaruser>  ",  "<Soar  6>”,  and  "[Ic]  <cl>  Some  prompts  that  would 
not  match  are  "foo",  "<soar ",  and  "%  ".  If  you  suspect  this  is  part  of  a  problem,  please  include  your  regular  Soar 
prompt  in  all  bug  reports. 

If  you  run  on  a  Sun,  we  include  a  file  in  the  distribution  provided  by  Josef  Nerb  called  sunfun-nj.el.  It  provides  an 
attempt  to  provide  a  uniform  mechanism  for  binding  Sun  function  keys.  We  have  not  tested  it,  but  Josef  and  Ronald 
Leenes  report  that  it  works.  If  all  of  your  machines  are  Suns,  you  should  put  in  the  soar-site  file  a  line  that  loads  it 
(i.e.,  (load  "sunfun-nj"))  and  insert  into  the  soar-site  file  their  suggestions  for  insertion  in  the  .emacs.  Otherwise  you 
can  point  it  out  to  users  as  something  they  can  load  in  their  .emacs  files. 
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Ij.  INCOMPATIBLE  CHANGES  FROM  PREVIOUS  VERSIONS 

*  Soai6  is  defined  as  a  dialect  of  Soar.  To  start  it  up,  type  M-x  Soar6.  To  change  its  image  name,  modify  the 
value  of  soar6-image*name  in  your  .emacs  file. 

*  inferior-soar-mode-map  is  now  isoar-mode-map. 

*  The  variable  soar-load-hook  has  been  replaced  by  the  more  appropriately  named  soar-mode-load-hook. 

*  C-z  has  been  rebound  to  access  the  new  outlining  commands.  You  can  change  it  by  setting  outline-prefix-char 
in  your  .emacs  to  another  character,  such  as  "VC-c'C-z". 

*  "Hooks"  variables  have  been  renamed  to  be  "hook"  variables.  This  is  more  consistent  with  Emacs  coding 
conventions.  For  example,  soar-mode-hooks  is  now  soar-mode-hook. 

*  The  variable  soar-image-arguments  has  gone  away.  You  must  either  define  a  shell  alias  or  holler  to  soar-bugs 
for  help. 

*  Several  keys  get  rebound,  including  C-x  o,  C-c.  You  can  rebind  them,  see  the  example  defaults  file,  soar-mode- 
defaults.el. 
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6.  Complete  keybindings  listing 

There  are  a  several  keymaps  around,  but  only  two  of  them  are  likely  to  be  interesting  to  you.  The  first, 
isoar-mode-map,  is  the  keymap  that  is  used  by  the  *soar*  buffer.  (This  buffer’s  mode  is  actually  inferior-soar- 
mode.  That  is  to  say,  it  is  running  an  inferior  process,  in  this  case  Soar,  and  is  designed  to  interact  with  that 
process.)  The  second  keymap,  soar-mode-map,  is  used  by  buffers  simply  in  soar-mode.  Soar-mode  is  used  when 
editing  buffers  filled  with  Soar  commands  or  productions.  The  two  m^s  share  a  large  number  of  keybindings  and 
differ  only  when  the  purposes  of  each  mode  diverge. 

A  complete  listing  of  the  keybindings  is  presented  below,  along  with  the  keybindings  of  lisp-mode  and  inferior- 
lisp-mode.  If  you  use  the  underlying  package.  ILISP,  to  edit  Lisp,  you  may  be  interested  in  these  maps  also. 

You  can  customize  your  keybindings  by  placing  code  to  rebind  your  favorite  keys  on  the  soar-mode-hook. 

Soar  Moda  keybindings: 


Leading : 

*  s  Different  between  soar-node  and  lisp-node, 

•f  w  Additions  to  soar-node  beyond  what  lisp-node  offers 
(l.e.,  unbound  by  lllsp) , 

1  «  Inferior  nodes  only  (l.e.,  those  with  a  running  Soar  or  lisp) . 

Otherwise  soar-node  Inherits  from  lisp-node  and  Isoar-mode  (Inferior 
soar  mode)  Inherits  from  lllsp-node  (Inferior  lisp  mode) . 


Changes  to  the  global  node  map: 


C-*  o 


LTD 

C-1 

] 

*  TAB 

*  tab 

DEL 
C-C 
1  C-a 
1  C-d 
1  RET 
RET 

C-x  C-f 
C-c  g 


popper-other-window 

(requires  a  C-u  prefix  to  get  to  popper  windows. 
Including  buffer  listings . ) 
newllne-and-lndent-llsp 
close-and-send-llsp 
close-all-lisp 

Ixident-llne-lllsp  ;  lisp-mode 

dabbrev-e^and  ;  during  expansion  In  taql-mode 

backward-delete-char-untablfy 

Prefix  Command 

bol-lllsp 

delete-char-or-pop-lllsp 
retum-lllsp 
newllne-and- Indent -lisp 
flnd-flle-llsp 

popper-grow-output  (overridden  In  soar-  and  lisp-modes) 


Control-c  map:  (order:  punctuation.  Caps,  small,  control) 


C-c 

1 

default -dlrectory-llsp 

1  C-c 

« 

raw-keys-lllsp 

C-c 

) 

flnd-unbalanced-llsp 

C-c 

0 

comnent-reglon-llsp 

C-c 

A 

edit -callers - lisp 

C-c 

. 

(d  1) 

C-c 

0 

(r  1) 

C-c 

1 

popper-bury-output 

*  C-c 

SPC 

mark-change-lisp 

17 


*  C-c 

SPC 

macrocyela  .-soar 

C-c 

TAB 

sand-lnvlslbla 

C-c 

* 

Prefix  Command 

C-c 

*  0 

clear-changea - lisp 

C-c 

*  c 

conpile-changea-llsp 

C-c 

*  • 

eval-cbangea -lisp 

C-c 

*  1 

list -changes - llap 

C-c 

A 

clman-apropos 

C-c 

B 

soar-pbreak-productlon 

C-c 

D 

clman 

C-c 

I 

Inspect -lisp 

*  C-c 

M 

macroea^and-llsp  ;ll8p 

*  C-c 

M 

full-matches  ;soar  (Soar  6  matches  1) 

*  C-c 

M-m 

really-full-matches  ;soar6  matches  2 

C-c 

P 

set -package-lisp 

i  C-c 

R 

costlnt  -Buearch-lnput  -aiatchlng 

C-c 

S 

select-lllap 

C-c 

T 

ptrace-soar 

C-c 

a 

argllat-llap 

C-c 

b 

swltch-to-llsp 

*  C-c 

c 

cooplle-defun-llsp  ;llsp 

*  C-c 

c 

soar-pclasa  ; soar 

C-c 

d 

documentation-lisp 

C-c 

• 

eval-defun-llsp 

+  C-c 

f 

aoar-flnd-tag 

C-c 

g 

abort-commands-llsp 

C-c 

1 

describe- lisp 

C-c 

k 

coB^lle-flle-llsp 

*  C-c 

1 

load-flle-llsp 

*  C-c 

1 

load-file-soar 

*  C-c 

m 

macroexpaxid-1-llsp  ;lisp 

*  C-c 

at 

sisatches  ;soar  .ooar  6  matches  0) 

C-c 

n 

eval-next-ses^-llsp 

*  C-c 

P 

package-lisp 

*  C-c 

P 

spr 

C-c 

r 

eval- region- lisp 

C-c 

8 

status -lisp 

C-c 

t 

trace-defun-llsp 

C-c 

V 

popper-scroll-output 

*  C-c 

w 

compile- region- lisp 

*  C-c 

w 

soar-copy-ap 

+  C-c 

X 

soar-excise-product Ion 

C-c 

y 

call-defun-llsp 

C-c 

z 

reset -lllsp 

+  C-c 

C-a 

taql-add-clause 

C-c 

C-c 

Interrupt -sub job-illsp  llisp-mode 

C-c 

C-b 

soar-load-buffer 

C-c 

C-c 

coaplle-def\in-and-go-llsp  ;  lisp-mode 

C-c 

C-d 

Insert -date-string 

C-c 

C-® 

eval-defun-and-go-llsp 

+  C-c 

C-f 

taql-flxup-construct 

C-c 

M-f 

flnd-productlon-ln-other-wlndow 

+  C-c 

C-1 

run-soar 
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+ 

C-c 

C-m 

zun-soaz-manu 

C-c 

C-n 

aval-naxt-saxp-and-go-lisp 

1 

C-c 

C-o 

comint -kill-output 

C-c 

C-r 

aval-raglon-and-go-llsp 

+ 

C-c 

C-t 

t aql- Insert -const ruct 

C-c 

C-w 

conplla-reglon-and-go-llsp 

1 

C-c 

C-u 

cosftlnt-klll-lnput 

+ 

C-c 

C-z 

outllne-coomands 

+ 

C-c 

C-z 

C-n 

Move  to  next  ▼Islbla  heading 

+ 

C-c 

C-z 

C-p 

Move  to  previous  visible  heading. 

+ 

C-c 

C-z 

C-f 

Forward  same  level. 

+ 

C-c 

C-z 

C-b 

Backward  same  level. 

+ 

C-c 

C-z 

C-u 

np  a  heading. 

+ 

C-c 

C-z 

C-a 

Show  all. 

+ 

C-c 

C-z 

C-s 

Show  sub-tree. 

+ 

C-c 

C-z 

C-i 

Show  children  (takas  arg  with  C-u) . 

+ 

C-c 

C-z 

C-a 

Show  entry. 

+ 

C-c 

C-z 

C-x 

Show  leaves. 

+ 

C-c 

C-z 

C-h 

Hide  subtree. 

+ 

C-c 

C-z 

C-t 

Hide  body. 

+ 

C-c 

C-z 

C-c 

Hide  entry. 

+ 

C-c 

C-z 

C-1 

Hide  leaves. 

Escap«  map: 

(order:  ptuictuatlon.  Caps,  small,  control) 

BSC 

tl 

replace-llsp 

ESC 

t 

next-de£lnltlon-llsp 

* 

BSC 

. 

edlt-def Inltlons-llsp  ; lisp 

* 

ESC 

. 

£lnd-tag  ; soar 

ESC 

? 

search-lisp 

BSC 

% 

next-caller-llsp 

ESC 

BET 

close-and-send-llsp 

ESC 

TAB 

coBq>leto-llsp 

+ 

ESC 

• 

taql  -aiqaand-const  ruct 

1 

ESC 

N 

comlnt-psearch-lnput 

i 

ESC 

P 

comint -msearch- Input 

i 

BSC 

n 

comint -next - Input 

i 

BSC 

P 

comint -previous -Input 

ESC 

q 

relndent-llsp 

i 

BSC 

s 

comint -prevlous-slmllar-lnput 

ESC 

C-1 

prevlous-bu££er-llsp 

ESC 

C-a 

beglnnlng-o£-de£un-llsp 

BSC 

C-® 

end-o£-da£un-llsp 

BSC 

C-q 

lndent-se3q>-lllsp 

ESC 

C-r 

reposltlon-wlndow-llap 

BSC 

C-x 

eval-de£un-llsp 
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7.  Default  startup  file 


Mod*:  Bmacs-Llsp 


ril*  :  •oar-iBod*-d*£attlt8.*l 

Author  :  Frank  Rlttar 

Cr*at*d  On  :  Wad  Jun  20 

Last  Modified  By:  Frank  Rlttar 

Last  Modified  On:  Wed  Nov  11  17:54:48  1992 

Update  Count  :  98 


How  to  load  GMD  Bmacs  Soar  mode 

This  file  contains  details  on  a  default  set  of  conanands  to  load  and  use 
soar  mode.  Movlce  users  with  wanllla  tastes  can  just  always  load  this, 
more  advanced  users  will  want  to  cut  and  paste  the  cosonands  out  of  this 
Into  their  .emacs  files 

To  use  Soarfi,  sierely  set  the  image  name  you  want  to  use  as 
soare-image-name,  and  call  the  function  Soar6  Instead  of  Soar. 

Loading  this  file  will  cause  the  following  major  changes  to  Emacs  to 
take  place: 

a)  The  file  cl. el  will  be  loaded  If  was  not  already  loaded. 

b)  Many  configuration  variables  will  have  been  set.  These  affect 

the  behavior  of  Soar  mode  and  the  code  on  top  of  which  it  is  built. 

c)  The  following  packages  will  be  autoloaded  when  the  listed  functions 
are  called: 

Package  Function 


XLISP  run-lllsp 

ILISP  allegro 

soar  soar 

d)  The  following  siapplngs  between  buffer  modes  and  file  name  patterns 
will  be  established,  causing  Bmacs  to  put  buffers  that  have  these 
file  extensions  be  put  Into  the  specified  mode  automatically: 

File  name  suffix  Mode 


.  soar  soar 

.  lisp  lisp-mode  (ilisp-version) 


;  TABLE  OF  CONTENTS 

1.  Variables  that  must  be  set 

;  11.  How  to  set  keyblndlngs  and  hooks 

111.  Load  associated  code 

;  Iv.  Grungy  things  you  have  to  do 

t 

changed  auto-mode-allst  to  ignore  .soar-aliases  27-Jul-92  -FER 


(require  'cl) 


;  Loaded  often-used  CL  extensions . 

;  we  will  use  things  here  like  pushnew 
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1 .  Varlablaa  that  must  be  set 

;;;  If  you  Insart  this  Into  your  .amacs,  this  Is  a  section  of  active  code  that 
;  you  can  not  eoimient  out  or  rmaovm. 

;  This  says  where  soar-mode  lives .  Do  not  end  the  pathname  with  ' / ' • 

(setq  soar-mode-home-dlrectory 

"/itf  s/cs/pro  ject/soar/5 . 2/eBiacs/soar/new'' ) 

; (setq  soar-image-name  . /stago/usr/doorenbs/soar6") 

(setq  soar-lamge-name  "/efs/cs/projeet/soar/5.2/2/bln/Fatax/mach/franz/Soar5") 
(setq  soarS-lmage-naiiie  "/efa/cs/project/soar/5 .2/emacs/soar/new/soar6*') 


; ;  Relative  pathname  off  of  soar-mode  for  lllsp-mode 
(setq  soar-lllsp-stibdlrectory  ''lllsp/4.12'*} 

;  tags  should  Include  taql  code  too . . . 

(setq  soar-default -tags-table  "DEFAULT-TAGS") 


;  11 .  Variables  that  can  be  set 

f  f  f 

;;;  These  variables  are  shown  with  their  default  values.  If  you  want  to 
; ; ;  change  their  values,  copy  this  file  (or  portions  of  this  file)  to  your 
; ; ;  directory  or  Insert  It  Into  your  . emacs  file . 

;;  The  variable  'soar-image-name'  must  contain  the  name  of  the  Soar 
; ;  executable  or  be  an  alias  which  runs  Soar.  It  must  be  something  which  is 
; ;  In  your  normal  comuuui  cucecutlon  path,  or  Emacs  will  not  be  able  to  find 
;;  It.  If  you  are  NOT  using  the  site  default  (set  In  'soar.el'},  then  you 
; ;  must  set  this  variable  manually. 

(setq  soar-image-name  "SoarS") 

; ;  If  t,  soar  commands  print  descriptions  Into  soar-diversion -buffer  (*glide*) 
;;  buffer.  If  nil,  dusgis  Into  *soar*  buffer. 

(setq  soar-prlnt-lnto-dlverslon-p  t) 

;;  Set  'llsp-no-popper'  to  't'  If  you  want  all  Lisp  loading  output  (as  opposed 
;  to  that  of  Soar  productions)  to  go  to  the  Inferior  Soar  buffer  rather  than 
; ;  Into  a  pop-up  window.  You  should  probably  also  sat  'comlnt-always-scroll' 

;  to  't'  as  well  so  that  output  Is  always  visible. 

;;  (setq  llsp-no-popper  nil)  ; default  Is  nil 
;;  (setq  comlnt-always-scroll  nil)  ; default  Is  nil 

; ;  Set  the  following  to  't'  to  print  out  the  month  In  'insert -date-string'  as 
;;  letters,  and  In  30-Oct-91  order,  rather  than  as  10-30-91. 

(setq  insert-date-wlth-month-name  nil)  ;  default  Is  nil 

;;  Set  to  'nil'  if  you  don't  want  'C-x  o'  to  skip  pop-up  buffers,  such 
; ;  as  '*Buf far  Menu*'  or  '*Help*' .  Default  is  't' . 

; ;  Can  also  be  set  to  a  list  of  pop-up  buffers  you  want  to  skip. 

(setq  popper-buffars-to-sklp  nil) 
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;  Pop  to  th«  CMS  (continuous  nsteh  sst)  buffer  1£  It  Is  being  written 
; ;  to  (default  'nil' ) . 

;  (setq  pop-to-ems  nil) 

;;  If  this  Is  C-^,  It  Is  also  C-6  unshlfted 
;;  (setq  soar-command -pref la  "\C-c") 

;;  The  outline  comnanda  are  bound  on  C-c  then  this  prefix  char. 

;;  (setq  outllne-preflx-char  "\C-x") 

; ;  If  soar-erase-dlverslon-buffer-p  is  t  (default) ,  erase  the  diversion 
;  buffer  each  time  you  use  It . 

(setq  soar-erase-dlverslon-buffer-p  t) 

;;  Name  of  the  diversion  buffer. 

;;  (setq  soar-dl version-buffer-name  '**glide**') 

;;  Popup  the  diversion  buffer  If  t  (the  default)  something  gets  put  In  there. 
;  (setq  soar-popup-dlverslon-buffer-p  t) 

; ;  soar-header-hoolcs  contains  a  list  of  what  to  put  on  the  header  when 
;;  make-header  Is  called.  The  default  Is  shown  below. 

/  0 

; ;  (setq  soar-header-hooks 

;;  ' (;;  a  top  line  with  mode  comes  for  free 

; ;  ; ;  a  divisor  line  comes  for  free 

; ;  header-blank 

;  header-f  lle-naune 

; ;  header-author 

; ;  header-creation-date 

; ;  header-modlf Icatlon-author 

; ;  header-modlf Icatlon-date 

; ;  header-update-count 

; ;  soar- vers Ion 

; ;  taql -version 

; ;  ; ; Put  PURPOSE  and  TOC  near  top 

header-blank 
;  header-purpose 

;  header-toc 

; ;  header-copyright 

; ;  ; ; Generally  want  either  RCS  stuff  or  header-history 

;;  ;;at  CMU  and  elsewhere,  fewer  users  and  fewer  non-hacky  use  RCS, 

; ;  header-dlvisor-llne 

header-status 
; ;  header-history 

;;  ; ;header-rcs-locker 

; ;  ; ; ; ; header-rcs-header 

; ;  ; ;header-rcs-log 

; ;  ; ;  divisor  line  comes  for  free 

) ) 

; ;  Soar  will  beep  when  initialized  if  t . 

; ;  (setq  soar-beep-after-setup-p  t) 
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il.  How  to  aet  ke^^lndlngs  and  hooks 

If  you  wish  to  change  the  ke^lndlngs  or  add  to  them  for  buffers  in 
soar-mode,  put  the  changes  on  the  'soar-hook'  in  your  .emacs  file 
with  code  conparable  to  the  code  below.  Similar  code  could  be  put  on 
the  'inferior-soar-mode-hook'  for  buffers  running  Soar. 

Here  is  an  exaxqple  of  a  soar-hook  function  which  defines  'C-c  C-t' 
to  run  function  'favorite-cmd'  in  both  Soar  mode  buffers  2md  Soar  process 
buffers;  and  redefines  a  mouse  button. 

Further  information  on  how  to  reset  the  atouse  keys  are  available  in  the 
soar-Biouse-x.el  file. 


;  Krample  set  up  for  stuff  to  do  when  putting  a  buffer  into  soar-mode 
(setq  soar-mode-hook 
'  ( (lambda  () 

(visit -tags-table  soar-default-tags-table) 

; ;  works  for  code  buffers 

(define-key  soar-mode-map  ''\c-z"  '  favorite-cmd2) 

; ;  this  command  rebinds  the  control  middle  mouse  to  what  it  was 
; ;  originally . 

(define-key  mouse-map  x-button-c-middle-up  ' x-cut-and-wipe-text) 

))) 

; ;  works  for  running  Soar  buffers 
(setq  soar-mode-hook 
' ((lambda  () 

(visit -tags -table  soar-default- tags -table ) 

(define-key  Isoar-mode-map  "\C-z”  ' favorite-cmd) 

; ;  this  command  rebinds  the  control  middle  mouse  to  what  it  was 
; ;  originally . 

(define-key  mouse-map  x-button-c-middle-up  'x-cut-and-wipe-text) 
))) 


Exaa^le  of  how  to  aet  soar-hook,  and  what  you  can  put  on  it,  which  gets 
gets  called  when  an  inferior  (running)  Soar  starts  up. 


(if  (not  (boundp  ' soar-hook) )  (setq  soar-hook  nil) ) 

; ;  soar-hook  gets  called  after  ilisp  inits,  but  before  soar  gets  called 
(setq  soar-hook 

(append  soar-hook 
'  ((lambda  () 

;  use  C-6  instead  of  C-c  as  command  prefix 
(setq  soar-command-prefix  "\C-6”) 

;  start  by  visiting  a  tags  table 
(visit-tags-table  "/af s/cs/pro ject/soar/5 . 2/2/lib/TAGS" ) 

; ;  ask  which  soar  I  want  iff  don' t  have  a  live  one 
(if  (and  (not  (comint -check-proc  "*aoar*")) 

(y-or-n-p 

"Use  (perhaps)  local  copy  of  Soar5-fsx(y)  or  SoarS  (n)  ?  ")) 
(setq  ilisp-program 

" / af s/cs/pro ject/soar/5 . 2/arc/sx/new/Soar5+sx . acli" ) ) 

; ;  or  just  always  use  a  single  version 
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(s«tq  lllsp-prograa 

"/•is/c8.cmu.«du/proj«ct/soar/5.2/2/bin/p*nax/inach/franz/Soar5”) ) ) 
; ;  set  header  notice 

(setq  header-copyright-notice  "Copyright  1991,  Frank  Ritter.") 

)))) 


ill.  Load  associated  code 

'utilltles/taql-indent-line.el'  provides  code  to  indent  TC' s  correctly 
when  using  soar-  or  taql-mode  (but  is  not  automatically  loaded  by 
soar-mode)  . 

(e.g.,  Set  up  ilisp  so  you  can  find  it  w/o  soar-mode.) 

We  believe  that  if  you  don't  use  ilisp  alone,  that  you  could  comment  or 
cut  this  out  to  save  space.  (But  I  wouldn't  do  that  if  I  were  you.) 


;  Establish  path  to  the  home  directory  of  Soar  mode  and  ILISP  mode. 

;  The  latter  is  set  here  so  that  you  can  use  ILISP  mode  independently 
;  of  Soar  mode: 


(pushnew  soar-mode-home-directory  load-path) 

(pushnew  (concat  soar-mode-home-directory  "/"  soar-ilisp-subdirectory) 
load-path) 

;  To  load  'utilities/taql-indent-line'  iff  it  has  not  been  loaded. 

; ;  Cut  this  into  your  soar-mode-hook,  if  you  wish. 

; ;  (require  ' taql-indent-line) 

; ;  Some  handy  things  for  working  on  just  lisp  that  you  are  carrying  around 
; ;  too,  let's  not  let  them  go  to  waste: 

(autoload  ' run-ilisp  "ilisp"  "Select  a  new  inferior  LISP."  t) 

(autoload  'allegro  "ilisp"  "Inferior  Allegro  Common  LISP."  t) 

; ;  Additional  useful  functions . 


(autoload  '  comint -mem  "comint" 

"Test  to  see  if  ITEM  is  equal  to  an  item  in  LIST. 
Option  cosparison  function  ELT^  defaults  to  equal."  t) 


(autoload  ' add-hook  "comint-ipc" 

"Add  a  function  to  a  hook  if  not  already  present.”  t) 

(autoload  ' soar-manual  "utilities/soar-maniial" 

"Read  an  online  manual,  such  as  for  Soar  or  soar-mode."  t) 


(autoload  'clman  "allegro/allegro-atode-init" 

"Read  about  a  specific  topic  in  the  online  CL  manual."  t) 

(autoload  ' clman-apropos  "allegro/allegro-mode-init" 

"List  topics  matching  a  subexpression  in  the  online  CL  manual."  t) 

; ;  set  the  ilisp-command-prefix  in  case  you  are  headed  into  ilisp  first 
(setq  ilisp-prefix  "\C~c") 
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;;;  Emacs  would  normally  put  .lisp  files  in  it's  default  single  lisp-mode. 
;;;  This  stakes  reading  a  lisp  file  load  in  ilisp. 

(add-hook  ' lisp-mode-hook 
(function 
(lambda  () 

(require  ' ilisp) ) ) ) 


iv.  Grungy  things  you  hawe  to  do 

This  is  live  code  that  you  have  to  have,  but  that  you  don' t  have  to 
understand  if  you  leave  it  alone. 


; ;  Put  files  that  end  in  . soar  into  soar-mode 
;  remove  comment  to  do  it  for  . Soar  files  too 

(defvar  soar-file-types 
' ("\\.soar$" 

;;  "\\.Soar$" 

"\\.soar5$" 

"\\.soar6$") ) 

(dolist  (suffix  soar-file-types) 

(if  (not  (assoc  suffix  auto-moda-alist) ) 

(push  (cons  suffix  'soar-mode)  auto-mode-alist) ) ) 

;;;  stake  calling  (run-soar,  soar,  soar-stode)  load  the  mode  code. 

(stapcar 

(function  (lasdoda  (x)  (autoload  (car  x)  "soar”  (car  (cdr  x) )  t) ) ) 

'  ((run-soar  "Starting  up  an  inferior  (buffer)  soar  process.") 

(soar  "Another  way  to  start  up  an  inferior  (buffer)  soar  process.'*) 

(soars  "Another  way  to  start  up  an  inferior  (buffer)  soar  process."} 
(soar-siode  "When  editing  a  file  of  Soar  productions  or  lisp  code.") 

)) 

(defun  Soar  () 

( interact ive ) 

(soar) ) 

; ; ; ;  This  should  be  covered  by  the  new  use-soar-mode-if-available  variable. 
;;;  If  taql-stOde  is  around,  put  .taql  files  into  soar-mode  as  the  major 
;  ;  mode  when  they  start  up,  with  taql -mode  behind 
; ; ;  This  works  if  soar-mode  is  loaded  second. 

;  (if  (assoc  "W.taql"  auto-mode-alist) 

;  (set-default  ' auto-mode-alist 
(append 

;  (mapcar  ' (lambda  (x) 

;  (cons  X  ' soar-and-taql-mode) ) 

;  ' ("\\.taql$")) 

;  auto-mode-alist) 


)) 


